docs: Add documentation for configuring service discovery with uptime tests #1154

buger · 2025-12-08T11:20:18Z

User description

Summary

Adds new documentation page explaining how to configure uptime tests to dynamically discover endpoints using service discovery
Addresses the documentation gap identified in DX-2022
Incorporates findings from TT-14943 regarding the correct JSON structure for query endpoints

What's Included

The new documentation page (uptime-tests-service-discovery.mdx) covers:

Introduction: Use cases and how the feature works
Prerequisites: Required setup before configuring
Query Endpoint JSON Structure: Examples for simple, nested, and target list formats
API Definition Configuration: Complete reference table with all options
Service Discovery Examples:
- Consul (with health endpoint)
- etcd (simple and nested JSON)
- Eureka (with JSON response)
Dashboard Configuration: Step-by-step UI instructions
Combining Static and Dynamic Tests: How to mix manual and discovered endpoints
Integration with Load Balancing: Using check_host_against_uptime_tests
Troubleshooting Guide: Common issues and solutions

Navigation Changes

Added the new page to docs.json under:

API Management → Deploy Tyk → Tyk Self Managed → Configuration

The page appears after "Uptime Tests" for logical navigation flow.

Test Plan

Verify the new page renders correctly in the documentation site
Check all internal links work correctly
Confirm JSON examples are syntactically valid
Review navigation placement in the sidebar

Related Issues

Resolves: DX-2022 (Documentation on Configuring Service Discovery for Uptime Tests)
Related: TT-14943 (Identify correct JSON returned by the Query Endpoint)

🤖 Generated with Claude Code

PR Type

Documentation

Description

Add new uptime tests discovery guide
Insert page into docs navigation
Provide JSON structures and configs
Include dashboard steps and troubleshooting

Diagram Walkthrough

flowchart LR
  Nav["Update docs.json navigation"] -- "add page link" --> Page["New guide: uptime-tests-service-discovery.mdx"]
  Page -- "covers" --> JSON["JSON structures & examples"]
  Page -- "includes" --> Config["API definition options"]
  Page -- "guides" --> UI["Dashboard setup steps"]
  Page -- "adds" --> Help["Troubleshooting & tips"]

File Walkthrough

Relevant files

Documentation

docs.json `Add service discovery doc to navigation` docs.json Add new page path under Configuration. Place after `uptime-tests` in sidebar.	+1/-0
uptime-tests-service-discovery.mdx `New guide: uptime tests with service discovery` planning-for-production/ensure-high-availability/uptime-tests-service-discovery.mdx New comprehensive guide for uptime tests discovery. Provide JSON path patterns and examples. Detail API/Dashboard configurations and load balancing. Add troubleshooting and related links.	+458/-0

… tests Add new documentation page explaining how to configure uptime tests to dynamically discover endpoints using service discovery. This addresses the gap identified in DX-2022 and incorporates findings from TT-14943 regarding the correct JSON structure for query endpoints. The documentation includes: - Prerequisites and introduction to the feature - Query endpoint JSON structure examples (simple, nested, target list) - Complete API definition configuration reference - Service discovery examples for Consul, etcd, and Eureka - Dashboard configuration steps - Instructions for combining static and dynamic tests - Integration with load balancing - Troubleshooting guide Resolves: DX-2022 Related: TT-14943 🤖 Generated with [Claude Code](https://claude.com/claude-code) Co-Authored-By: Claude <[email protected]>

github-actions · 2025-12-08T11:21:18Z

PR Reviewer Guide 🔍

Here are some key observations to aid the review process:

⏱️ Estimated effort to review: 2 🔵🔵⚪⚪⚪
🧪 No relevant tests
🔒 No security concerns identified
⚡ Recommended focus areas for review Possible Inaccuracy The config table marks `data_path` as required; however, some discovery responses may rely on `parent_data_path` with `use_nested_query` and/or `use_target_list` where paths may differ. Verify required/optional flags align with actual Gateway behavior and whether `data_path` is always mandatory. ### Configuration Options \| Option \| Type \| Required \| Description \| \| :--- \| :--- \| :--- \| :--- \| \| `use_discovery_service` \| boolean \| Yes \| Set to `true` to enable service discovery for uptime tests \| \| `query_endpoint` \| string \| Yes \| The URL of your service discovery endpoint (Consul, etcd, Eureka, etc.) \| \| `data_path` \| string \| Yes \| The JSON path to the hostname/address field in the response \| \| `parent_data_path` \| string \| No \| Used with `use_nested_query` to specify the path to a JSON-encoded string containing the actual data \| \| `port_data_path` \| string \| No \| The JSON path to the port field if separate from hostname \| \| `use_nested_query` \| boolean \| No \| Set to `true` if the endpoint data is within a JSON-encoded string \| \| `use_target_list` \| boolean \| No \| Set to `true` if the response contains multiple endpoints \| \| `cache_timeout` \| integer \| No \| How long (in seconds) to cache the discovered endpoints. Default: 60 \| \| `target_path` \| string \| No \| A path to append to discovered endpoints (e.g., `/health` for health check endpoints) \| JSON Path Semantics Examples use dotted paths like `Service.Address`, `services.address`, and `port.$`. Confirm these match the exact JSONPath syntax supported by Tyk for uptime test discovery (e.g., arrays handling, nested fields). Mismatch could confuse users. ## Service Discovery Examples ### Consul Example Consul's health endpoint returns healthy service instances. Configure Tyk to query Consul and extract service addresses: Query Endpoint: http://consul:8500/v1/health/service/my-api?passing=true Sample Response: ```json [ { "Node": { "ID": "node-1", "Node": "consul-node-1", "Address": "10.0.0.1" }, "Service": { "ID": "my-api-1", "Service": "my-api", "Address": "10.0.0.1", "Port": 8080 } }, { "Node": { "ID": "node-2", "Node": "consul-node-2", "Address": "10.0.0.2" }, "Service": { "ID": "my-api-2", "Service": "my-api", "Address": "10.0.0.2", "Port": 8080 } } ] Configuration: { "uptime_tests": { "service_discovery": { "use_discovery_service": true, "query_endpoint": "http://consul:8500/v1/health/service/my-api?passing=true", "data_path": "Service.Address", "port_data_path": "Service.Port", "use_target_list": true, "cache_timeout": 30, "target_path": "/health" } } } </details> <details><summary><a href='https://github.com/TykTechnologies/tyk-docs/pull/1154/files#diff-b7b4169fa5b2e02aa17d40553a73c5d9520086753c501eeb926c63b162bb6d9eR133-R150'><strong>Nav Placement</strong></a> New page is inserted after "uptime-tests". Confirm sidebar ordering and grouping match docs conventions and that the slug matches the file path to avoid broken links. </summary> ```json "deployment-and-operations/tyk-self-managed/tyk-demos-and-pocs/overview", "tyk-self-managed/install", { "group": "Configuration", "pages": [ "planning-for-production", "planning-for-production/database-settings", "planning-for-production/ensure-high-availability/circuit-breakers", "planning-for-production/ensure-high-availability/enforced-timeouts", "planning-for-production/ensure-high-availability/health-check", "planning-for-production/ensure-high-availability/load-balancing", "planning-for-production/ensure-high-availability/service-discovery", "planning-for-production/ensure-high-availability/uptime-tests", "planning-for-production/ensure-high-availability/uptime-tests-service-discovery", "configure/external-service", "tyk-configuration-reference/kv-store", "planning-for-production/monitoring/tyk-components", "tyk-configuration-reference/redis-cluster-sentinel",

github-actions · 2025-12-08T11:21:47Z

PR Code Suggestions ✨

Explore these optional code suggestions:

Category	Suggestion	Impact
General	Use supported admonitions Replace the custom tag with the site's supported admonition syntax to avoid rendering errors. If MDX doesn't register a `Note` component, use fenced admonitions or a standard blockquote. planning-for-production/ensure-high-availability/uptime-tests-service-discovery.mdx [298-300] -<Note> -Eureka returns XML by default. To receive JSON, either configure your Eureka endpoint or use Tyk to add an `Accept: application/json` header via an API definition that proxies to Eureka. -</Note> +> Note: +> Eureka returns XML by default. To receive JSON, either configure your Eureka endpoint or use Tyk to add an `Accept: application/json` header via an API definition that proxies to Eureka. Suggestion importance[1-10]: 6 __ Why: Replacing a custom Note tag with a standard admonition or blockquote can prevent rendering errors if `Note` isn’t registered. It’s a safe, readability-focused improvement but not critical.	Low
General	Ensure table renders reliably If the docs site uses CommonMark without a table plugin, this pipe table might not render. Convert to a simple list to ensure compatibility and prevent broken formatting in static site builds. planning-for-production/ensure-high-availability/uptime-tests-service-discovery.mdx [141-154] ### Configuration Options -\| Option \| Type \| Required \| Description \| -\| :--- \| :--- \| :--- \| :--- \| -\| `use_discovery_service` \| boolean \| Yes \| Set to `true` to enable service discovery for uptime tests \| -\| `query_endpoint` \| string \| Yes \| The URL of your service discovery endpoint (Consul, etcd, Eureka, etc.) \| -\| `data_path` \| string \| Yes \| The JSON path to the hostname/address field in the response \| -\| `parent_data_path` \| string \| No \| Used with `use_nested_query` to specify the path to a JSON-encoded string containing the actual data \| -\| `port_data_path` \| string \| No \| The JSON path to the port field if separate from hostname \| -\| `use_nested_query` \| boolean \| No \| Set to `true` if the endpoint data is within a JSON-encoded string \| -\| `use_target_list` \| boolean \| No \| Set to `true` if the response contains multiple endpoints \| -\| `cache_timeout` \| integer \| No \| How long (in seconds) to cache the discovered endpoints. Default: 60 \| -\| `target_path` \| string \| No \| A path to append to discovered endpoints (e.g., `/health` for health check endpoints) \| +- `use_discovery_service` (boolean, required): Set to `true` to enable service discovery for uptime tests. +- `query_endpoint` (string, required): The URL of your service discovery endpoint (Consul, etcd, Eureka, etc.). +- `data_path` (string, required): The JSON path to the hostname/address field in the response. +- `parent_data_path` (string, optional): Used with `use_nested_query` to specify the path to a JSON-encoded string containing the actual data. +- `port_data_path` (string, optional): The JSON path to the port field if separate from hostname. +- `use_nested_query` (boolean, optional): Set to `true` if the endpoint data is within a JSON-encoded string. +- `use_target_list` (boolean, optional): Set to `true` if the response contains multiple endpoints. +- `cache_timeout` (integer, optional): How long (in seconds) to cache the discovered endpoints. Default: 60. +- `target_path` (string, optional): A path to append to discovered endpoints (e.g., `/health` for health check endpoints). Suggestion importance[1-10]: 5 __ Why: Converting pipe table to a list can improve compatibility if the site lacks table support. Impact is moderate and context-dependent; the current table may already render fine.	Low
Possible issue	Prevent broken sidebar link Ensure the new sidebar entry `uptime-tests-service-discovery` matches the actual file path and slug. If the sidebar expects file paths without extension, verify routing builds correctly; otherwise include `.mdx` to prevent broken links. docs.json [146-148] "planning-for-production/ensure-high-availability/uptime-tests", -"planning-for-production/ensure-high-availability/uptime-tests-service-discovery", +"planning-for-production/ensure-high-availability/uptime-tests-service-discovery.mdx", "configure/external-service", Suggestion importance[1-10]: 4 __ Why: The suggestion is reasonable but speculative; many doc sites resolve slugs without extensions. It could prevent a broken link if the build requires .mdx, but correctness depends on site config.	Low

buger mentioned this pull request Dec 8, 2025

🔄 Preview: docs: Add documentation for configuring service discovery with uptime tests #1155

Draft

4 tasks

github-actions bot added the Review effort 2/5 label Dec 8, 2025

mintlify bot deployed to staging December 8, 2025 11:26 View deployment

Merge main into docs/DX-2022-uptime-tests-service-discovery

1f225cf

mintlify bot deployed to staging December 9, 2025 05:57 View deployment

Merge main into docs/DX-2022-uptime-tests-service-discovery

fef37ad

mintlify bot deployed to staging December 9, 2025 06:04 View deployment

Merge main into docs/DX-2022-uptime-tests-service-discovery

ecf038c

mintlify bot deployed to staging December 9, 2025 06:07 View deployment

Merge main into docs/DX-2022-uptime-tests-service-discovery

d823c27

mintlify bot deployed to staging December 9, 2025 06:12 View deployment

sharadregoti marked this pull request as draft December 9, 2025 10:41

Provide feedback

Saved searches

Use saved searches to filter your results more quickly

docs: Add documentation for configuring service discovery with uptime tests #1154

docs: Add documentation for configuring service discovery with uptime tests #1154

Uh oh!

buger commented Dec 8, 2025 •

edited by github-actions bot

Loading

Uh oh!

github-actions bot commented Dec 8, 2025

Uh oh!

github-actions bot commented Dec 8, 2025

Uh oh!

Reviewers

Assignees

Labels

Projects

Milestone

Development

Uh oh!

2 participants

docs: Add documentation for configuring service discovery with uptime tests #1154

Are you sure you want to change the base?

docs: Add documentation for configuring service discovery with uptime tests #1154

Uh oh!

Conversation

buger commented Dec 8, 2025 • edited by github-actions bot Loading Uh oh! There was an error while loading. Please reload this page.

Uh oh!

User description

Summary

What's Included

Navigation Changes

Test Plan

Related Issues

PR Type

Description

Diagram Walkthrough

File Walkthrough

Uh oh!

github-actions bot commented Dec 8, 2025

PR Reviewer Guide 🔍

Uh oh!

github-actions bot commented Dec 8, 2025

PR Code Suggestions ✨

Uh oh!

Reviewers

Assignees

Labels

Projects

Milestone

Development

Uh oh!

2 participants

buger commented Dec 8, 2025 •

edited by github-actions bot

Loading